IMPORTANT: Read the document "Upgrading", even if you've never used the framework before. It points out some CRUCIAL changes to the framework that you must be aware of.
You should also always read the "Version History", since many new aspects of the framework are only documented there.
Description:
Grant's CGI Framework is a framework for writing 68K & PowerPC Macintosh CGI applications, and WebSTAR Plug-Ins, in C. The user of the framework only needs to modify one function (located in its own file) to produce a custom CGI - all the other details can be left to the framework. However, there are extensive options for customization available for those who need them - and full source code is provided.
Macintosh programming experience is not required (although it helps) - but at least a basic knowledge of the ANSI C language is required.
* Automatic html form parsing with easy function access to individual data fields
* Asynchronus CGI (ACGI) support
* ListSTAR trigger and action events
* AppleScriptable for testing without a server or network
* Optional compile as faceless background-only application
* Numerous configuration options for optimizing to your specific needs
* Optional self-quitting after specified idle time
* Significant performance increase over scripts such as those in AppleScript and Perl
* Full source code included
* Metrowerks and Symantec project files
* If you use it to write free applications, it's free to use. (Others see "Legal&Money" folder)
Requirements:
- Applications compiled with the framework will require Macintosh System 7 or later
- A Macintosh C compiler (Metrowerks and Symantec are supported)
- WebSTAR API SDK from StarNine Technologies (if you want to compile WSAPI plug-ins)
<http://www.starnine.com/webstar/webstarsdk.html>
- Version 2.1 (or later) of Apple’s Universal Headers (included with current commercial compilers). <ftp://ftpdev.info.apple.com/Developer_Services/Development_Kits/Interfaces_%26_Libraries/Interfaces/>
Getting Started
The 'Documentation' folder contains some (currently incomplete) instructions on how to use the framework, the version history (some items are only documented in the version history, so read it!) and the 'License and Limited Warranty'. If you read through the entire documentation (shouldn't take very long because there's not all that much, yet), look at the source code, and still don't understand something, ask about it on the mailing list or by email directly to Grant. (addresses later in this doc)
Notes:
Project files for earlier versions of Codewarrior and Symantec environments may be made available. Please send email to grant@kagi.com requesting the particular version you want if you can't figure out your own project file.
I've only added basic support for ListSTAR trigger and action events in the current version.
Send Partial support doesn't seem to be very stable yet - use with caution.
For those who don't want both CGI and ListSTAR events in their application, it is easy to remove the ListSTAR or CGI support from the project. See the section on "Building a ListSTAR tool", at the end of the documentation file, for instructions on using or not using ListSTAR and CGI events.
For specifics on what you have to pay for using this software and code (if you're not using it to create publicly distributed freeware), please refer to the "Royalties" file in the "Documentation" folder.
This is beta software but it seems to generally work without problems! Don't bet your life on it though...
Further Information About This Framework
World Wide Web home page:
http://arpp.carleton.ca/cgi/framework/
Grant's CGI Discussion, Announcements, and the Source Updates mail lists:
I've set up a mailing list for discussing this framework. It is intended to be a forum for information, ideas, questions and announcements about about writing CGIs (and the CGIs that have been written) using Grant's CGI Framework.
Send a message with the command "subscribe" (without quotes) as the subject to:
grantcgi@arpp.carleton.ca
There is a list for those who only want the announcements - no discussion. It is mutually-exclusive with the grantcgi list, meaning that you can only subscribe to one of them since all the postings to grantcgi-announce are also made to grantcgi.
Send a message with the command "subscribe" (without quotes) as the subject to:
grantcgi-announce@arpp.carleton.ca
You can also subscribe to a mailing list which will send you periodic updates to the framework as they are released (both interm and regular releases). All updates are sent as Stuffit attachments (HQX MIME format). The archives are not sent to either of the two other lists.
Send a message with the command "subscribe" (without quotes) as the subject to:
grantcgi-source@arpp.carleton.ca
If you want more details on any of the lists, just send the command "help" instead of "subscribe".
Download:
http://arpp.carleton.ca/cgi/grantscgi.sit.hqx
Info-Mac ftp archives in "/info-mac/dev/lib/"
Apprentice CD "The Definitive Collection of Source Code and Utilities for Mac Programmers" <http://www.celestin.com/apprentice/>
'CDWeb' Vol. 11 CD included with the Japanese "Internet User" Magazine, 1995 No. 12. in "CDWeb Vol. 11:Starter Kit:WWW:Server:CGI:grants-cgi-framework-10b10:"
Symantec C++: "Symantec C++ v8 Release 5:Third Party Goodies:Source/Libraries:grantscgi:" (1.0b13)
My list seems to grow faster than I get things on it done... With this in mind, I'll encourage you once again to contribute your feature requests. Please take special note of the last section of this list and let me know if you can contribute to any of the items there. Help and suggestions are always welcome with all aspects of the framework. The full (current) list is at:
http://arpp.carleton.ca/cgi/framework/todo.html
These are the remaining tasks on my list before version 1.0 is finalized:
* Get Send Partial working well
* Finish WebSTAR CFM Plug-in support
* Documentation
* Locating and fixing bugs
* Optimizing
Other areas I intend to work on:
* MOS web server plug-in API
* Write some useful test scripts
* MPW support (anybody do make files?)
* MacAPP, PowerPlant and THINK Class Library C++ CGI class integration
* Pascal version
* Support unix cgi variables for easier porting from unix
* AppleGuide, QuickView, THINK Reference, etc. online reference(s)
* Profile and optimize the code
* HTTP file upload
Acknowledgements
The following are some of the people (alphabetically listed) who've contributed to and affected this framework (But don't blame them for the outcome, please. It's all my fault.) I've probably left some people out who should be listed - my apologies to them.
Scott T Boyd and a bunch of others who were at MacHack'95 affected my thinking about this code.
Gregory S. Combs identified the now corrected PowerPC compiler errors and supplied the initial PPC format project file for CodeWarrior and some code snippets. He's also made various other useful comments & contributions.
Rick Hartmann of Symantec Macintosh Dev Tools Support helped me figure out my problems getting the framework to compile with Symantec's tools.
Devon Hubbard for creating QC™ and for helping me at MacHack'96.
Steve Johnson was another person who identified the now corrected PowerPC compiler errors.
Frank Leahy has given me a lot of good suggestions and has also identified some bugs.
Peter N Lewis and Quinn developed the Internet Config system.
John Norstad's MailTools Gateway was another framework I looked at, but decided the code was too obscure for my very particular code style tastes. (Not that my code is necessarily any less obscure - just differently so ;-)
John O'Fallon wrote the "Responder" source which inspired this framework. Although I did the whole thing over from scratch to suit my own purposes. See his site: http://www.maxum.com/maxum/
Chuck Shotton, author of MacHTTP™ and WebSTAR™, answered some of my questions along the way, and kindly granted permission to include his cgi_params page with the framework.
Stefan Strand of "Teknik i Media AB" identified my off-by-one error in the 'CGIDecodeSpecialChars' function (now fixed).
Scott Taylor pointed out the missing '/' in my TITLE tags in the sample html, as well as a bug in 'startupTrapAvailable'.
Wayne K. Walrath identified (and helped solve) my previously bad design of AppleEvent threading.
The WebSTAR™ documentation provided the details of the WWWΩsdoc AppleEvent.
And, with much pride, I can thank the registered users who are financially supporting my work. It is much appreciated!
About the Author
Grant Neufeld is the author of a number of Macintosh CGIs, as well as the "Mac WWW FAQ".
See my CGIs pages for information about my other CGI projects:
http://arpp.carleton.ca/cgi/
The Mac WWW FAQ:
http://arpp.carleton.ca/mac/
See my vanity page for more insight into who I am and what I do:
http://arpp.carleton.ca/grant/
Contacting me (use one of):
gneufeld@ccs.carleton.ca
grant@kagi.com
grant@acm.org
____________________
StarNine, ListSTAR, and WebSTAR are trademarks of StarNine Technologies, Inc.
AppleScript, Macintosh, Mac, and MacTCP are trademarks or registered trademarks of Apple Computer, Inc.
UNIX is a registered trademark of Novell, Inc.
CodeWarrior is a trademark of Metrowerks Inc.
Symantec is a trademark of Symantec Corporation.
WorkSMART is a trademark of InfoDesign Corporation.
Grant's CGI Framework is, for those who even bother to read the small print, a GrantMark and a TradeMark of Grant Neufeld.
